QuickTime 3 Reference

| Previous | Chapter Contents | Chapter Top | Next |

Groups

It can sometimes be valuable to group a set of parameters together. For example, you might want to align the labels of the parameters in a group, or enclose a set of parameters with a box in the user interface. The grouping mechanism allows you to specify a set of parameters and the attributes that are applied to the group.

If the parameter data type and ID atom of a description contains child atoms, rather than data, it defines a group. A group is a set of related atoms, where the relationship amongst them can be based on attributes such as:

• layout--for example, the group is a set of text labels that should be aligned.
• spatial--for example, the items in the group should be placed side by side to optimize dialog box layout.
• naming--the items in the group are related controls that should be displayed under a single heading in the dialog box.
• usage--a pair of long integers may together specify a co-ordinate. In this case, they can be grouped together and the group's parameter data usage atom set to kParameterUsagePoint .

Groups can be nested within one another as needed. Groups can optionally have a name, which allows your application to place grouped parameters within a panel or tabbed group under that name.

Listing 32 shows an example of a group, which in this case contains a single parameter description.

Listing 32 An example group atom from an 'atms' resource definition.

kParameterAtomTypeAndID, 100, noChildren,
{
    OSType { "none" };      // Use 'none' as this is not a real parameter
    long { "0" };
    kAtomNoFlags;
    string { "" };
};

kParameterDataBehavior, 100, noChildren,
{
    kParameterItemGroupDivider; // Use a divider to separate this group
    kGroupNoFlags;
};

kParameterDataType, 100, 1*5,   // 1 parameter * 5 atoms to describe each
                                //parameter
{
};

kParameterAtomTypeAndID, 3, noChildren,
{
    OSType { "pMul" };
    long { "1" };
    kAtomNotInterpolated;
    string { "Pre-multiply color" };
};

kParameterDataType, 3, noChildren,
{
    kParameterTypeDataRGBValue;
};

kParameterDataRange, 3, noChildren,
{
    short { "0" };
    short { "0" };
    short { "0" };
    short { "65535" };
    short { "65535" };
    short { "65535" };
};

kParameterDataBehavior, 3, noChildren,
{
    kParameterItemColorPicker;
    long { "0" };
};

kParameterDataDefaultItem, 3, noChildren,
{
    short { "65535" };
    short { "65535" };
    short { "65535" };
};


Enumeration Lists

When an enumerated type is required for a parameter value, a new enumeration list is placed directly into the root atom container. Enumeration lists are arrays of name-and-value pairings in the following format:

typedef struct
{
    long    value;
    Str255  name;
} EnumValuePair;

typedef struct
{
    long            enumCount;  // number of enumeration items to follow
    EnumValuePair   values[1];  // values and names for them
} EnumListRecord;


The type of an enumeration list atom is kParameterEnumList ( 'enum' ). Listing 33 shows an enumeration list that contains three elements.

Listing 33 An example enumeration list from an 'atms' resource definition.

kParameterEnumList, 1, noChildren,
{
    long { "3" };           // No of elements in the enum

    long {"1"}; string { "Straight Alpha" };
    long {"2"}; string { "Pre-multiply Alpha" };
    long {"3"}; string { "Reverse Alpha" };
};


Source Count

The source count atom ( kParameterSourceCountName , 'srcs' ) contains a single long integer value that defines the maximum number of sources that this effect can accept. The atom is always placed in the root atom container of the parameter description.

The source count atom is required.